home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / misc / xref_v1.1.lha / XRef / Doc / english / xref.doc < prev    next >
Encoding:
Text File  |  1995-01-09  |  32.4 KB  |  907 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. xref.library/--background--
  6. xref.library/AddXRefDynamicNode
  7. xref.library/CloseXRefFile
  8. xref.library/CreateXRefFileA
  9. xref.library/FindXRefFile
  10. xref.library/GetXRefBaseAttrsA
  11. xref.library/GetXRefConfigDir
  12. xref.library/GetXRefFileAttrsA
  13. xref.library/LoadXRefPrefs
  14. xref.library/LockXRefBase
  15. xref.library/ParseXRef
  16. xref.library/RemoveXRefDynamicNode
  17. xref.library/SetXRefBaseAttrsA
  18. xref.library/SetXRefFileAttrsA
  19. xref.library/UnlockXRefBase
  20. xref.library/WriteXRefFileEntryA
  21. xref.library/XR_ExpungeXRef
  22. xref.library/XR_LoadXRef
  23.  
  24.  
  25. xref.library/--background--                        xref.library/--background--
  26.  
  27.     PURPOSE
  28.         the xref.library implements a pattern matching for xrefentries off
  29.         all kinds.This is managed by categories and files.A category is a
  30.         group of xreffiles, which have a relationship of a/some aspect(s).
  31.         You can access a entry via a category or just an file. See the
  32.         XREFA_#? defines for this. For example the following four files are
  33.         grouped together in four main categories :
  34.             1)  sys_autodoc.xref  -> CATEGORY SysAutoDoc
  35.             2)  xref_autodoc.xref -> CATEGORY XRefAutoDoc
  36.             3)  sys_include.xref  -> CATEGORY SysInclude
  37.             4)  xref_include.xref -> CATEGORY XRefInclude
  38.  
  39.         The following categories matches the listed xreffiles :
  40.                 #?AutoDoc  -> 1,2
  41.                 #?Include  -> 3,4
  42.                 Sys#?      -> 1,3
  43.                 XRef#?     -> 2,4
  44.  
  45.     ENVIRONMENT
  46.         The xref.library uses two environment variables. First the
  47.         XREFCONFIGDIR for the configuration of the XRef-System. You can
  48.         specify with this env-variable, where you have all configuration
  49.         files for the XRef-System.
  50.         The second XREFDIR is set from the library to have an access from
  51.         the shell to the global xref directory ! This variable is changed,
  52.         if you specify a new global xref directory via SetXRefBaseAttrs() !
  53.  
  54.     PREFS
  55.         the xref.library can be configured by a prefs file. If the library
  56.         is opened the first time it looks for a file in xref.prefs. First it
  57.         tries to get the directory from the XREFCONFIGDIR env-variable.
  58.         If this doesn't exists it uses the "sys:config/xref" directory to
  59.         open the xref.prefs file. If this file exists, it reads it via the
  60.         LoadXRefPrefs() function.
  61.  
  62.     SEE ALSO
  63.         GetXRefConfigDir(), LoadXRefPrefs()
  64.  
  65. xref.library/AddXRefDynamicNode                xref.library/AddXRefDynamicNode
  66.  
  67.     NAME
  68.         AddXRefDynamicNode - adds the xref.library dynamic node host to the
  69.                              amigaguide system
  70.  
  71.     SYNOPSIS
  72.         success = AddXRefDynamicNode();
  73.           D0
  74.  
  75.         BOOL AddXRefDynamicNode(void);
  76.  
  77.     FUNCTION
  78.         adds the xref.library dynamic node host to the amigaguide system.
  79.         This enables the xref.library to generate a main page with all
  80.         referenced files actually in the system or for a specified
  81.         category.
  82.  
  83.     INPUTS
  84.         none
  85.  
  86.     DYNAMIC NODES
  87.         The following names represent the dynamic nodes of the xref.library :
  88.  
  89.         xref.library_xreffile@main - This node displays all xreffiles,
  90.             which are in memory.
  91.  
  92.         xref.library_xreffile@<filename> - This node displays all files in
  93.             the xreffile specified by the <filename>.
  94.  
  95.         xref.library_xreftype@Generics - This node displays all entries of
  96.             the XREFT_GENERIC type.
  97.  
  98.         xref.library_xreftype@Functions - This node displays all entries of
  99.             the XREFT_FUNCTION type
  100.  
  101.         xref.library_xreftype@Commands - This node displays all entries of
  102.             the XREFT_COMMAND type
  103.  
  104.         xref.library_xreftype@Includes - This node displays all entries of
  105.             the XREFT_INCLUDE type
  106.  
  107.         xref.library_xreftype@Macros - This node displays all entries of
  108.             the XREFT_MACRO type
  109.  
  110.         xref.library_xreftype@Structures - This node displays all entries of
  111.             the XREFT_STRUCT type
  112.  
  113.         xref.library_xreftype@Typedefs - This node displays all entries of
  114.             the XREFT_TYPEDEF type
  115.  
  116.         xref.library_xreftype@Defines - This node displays all entries of
  117.             the XREFT_DEFINE type
  118.  
  119.     RESULTS
  120.         result TRUE for success otherwise FALSE, perhaps there is no
  121.         amigaguide.library or something else
  122.  
  123.     SEE ALSO
  124.         RemoveXRefDynamicNode(), ParseXRef()
  125.  
  126. xref.library/CloseXRefFile                          xref.library/CloseXRefFile
  127.  
  128.     NAME
  129.         CloseXRefFile - closes and free's all allocated resources for a
  130.             created xreffile via CreateXRefFileA()
  131.  
  132.     SYNOPSIS
  133.         CloseXRefFile(handle);
  134.                         A0
  135.  
  136.         void CloseXRefFile(struct XRefFileHandle *);
  137.  
  138.     FUNCTION
  139.         this function closes the created xreffile and free's all resources
  140.         allocated from CreateXRefFileA() and WriteXRefFileEntryA().
  141.         Currently all entries are buffered, so only this function writes the 
  142.         data to the disk.
  143.  
  144.     INPUTS
  145.         handle (struct XRefFileHandle *) - handle pointer returned from
  146.             CreateXRefFileA()
  147.  
  148.     RESULTS
  149.         none
  150.  
  151.     SEE ALSO
  152.         CreateXRefFileA(), WriteXRefFileEntryA()
  153.  
  154. xref.library/CreateXRefFileA                      xref.library/CreateXRefFileA
  155.  
  156.     NAME
  157.         CreateXRefFileA - create a xreffile
  158.         CreateXRefFile - varargs stub for CreateXRefFileA
  159.  
  160.     SYNOPSIS
  161.         handle = CreateXRefFileA(file,taglist);
  162.           D0                      A0     A1
  163.  
  164.         handle = CreateXRefFile(file,tag1,...);
  165.  
  166.         struct XRefFileHandle *CreateXRefFileA(STRPTR ,struct TagItem *);
  167.  
  168.         struct XRefFileHandle *CreateXRefFile(STRPTR,Tag1,...);
  169.  
  170.     FUNCTION
  171.         this function creates an xreffile and allocates all needed resources.
  172.         It returns a handle, which is used by the WriteXRefFileEntryA() and 
  173.         CloseXRefFile() calls. If you get a handle to the created xreffile ,
  174.         you must call the CloseXRefFile() function. Otherwise the file isn't
  175.         closed and no resources are free'd
  176.  
  177.     TAGS
  178.         XREFA_Priority (BYTE) - specifies a default priority, which is saved
  179.             internally in the xreffile. If no priority is specified via
  180.             XR_LoadXRef() function call, this priority is used.
  181.  
  182.         XREFA_File (STRPTR) - this tag overrides the file parameter
  183.  
  184.         XREFA_Category (STRPTR) - specifies a build-in category.This category
  185.             can't be overwritten with a XR_LoadXRef() call.
  186.  
  187.         XREFA_Name (STRPTR) - defines a name for this xreffile.If this tag
  188.             isn't set. The filename is used as the name.
  189.  
  190.         XREFA_VersTag (STRPTR) - this tag is used to write an AmigaDOS 2.0
  191.             version-string.
  192.  
  193.         XREFA_Author (STRPTR) - specifies the author of this xreffile.
  194.  
  195.         XREFA_Path (STRPTR) - path to use for all entries in this xreffile.
  196.  
  197.     INPUTS
  198.         file (STRPTR) - file to create, if you specify only a filename
  199.             without any path part, this file is created in the global xref-
  200.             file directory.See XREFBA_XRefPath tag.
  201.         taglist (struct TagItem *) - pointer to an array of tagitems.
  202.         tag1 (Tag) - first tag used in varargs stub.
  203.  
  204.     RESULTS
  205.         handle (struct XRefFileHandle *) - handle pointer or NULL for an
  206.             failure
  207.  
  208.     SEE ALSO
  209.         WriteXRefFileEntryA(), CloseXRefFile()
  210.  
  211. xref.library/FindXRefFile                            xref.library/FindXRefFile
  212.  
  213.     NAME
  214.         FindXRefFile - find a xreffile with a given name
  215.  
  216.     SYNOPSIS
  217.         xreffile = FindXRefFile(name);
  218.            D0                    A0
  219.  
  220.         struct XRefFileNode *FindXRefFile(STRPTR);
  221.  
  222.     FUNCTION
  223.         this function searches for xreffile with the given name. If there
  224.         exists a xreffile with this name, it returns a pointer to it. This
  225.         pointer is a handle for GetXRefFileAttrsA()/SetXRefFileAttrsA().
  226.  
  227.     INPUTS
  228.         name (STRPTR) - name to search for
  229.  
  230.     RESULTS
  231.         xreffile (struct XRefFileNode *) - pointer to the xreffile. This is
  232.             only a handle for the appropriate functions !
  233.  
  234.     SEE ALSO
  235.         GetXRefFileAttrsA(), SetXRefFileAttrsA()
  236.  
  237. xref.library/GetXRefBaseAttrsA                  xref.library/GetXRefBaseAttrsA
  238.  
  239.     NAME
  240.         GetXRefBaseAttrsA - get global xref.library attributes
  241.         GetXRefBaseAttrs - varargs stub for GetXRefBaseAttrsA()
  242.  
  243.     SYNOPSIS
  244.         num = GetXRefBaseAttrsA(tagList);
  245.          D0                        A0
  246.  
  247.         num = GetXRefBaseAttrs(Tag1,...);
  248.  
  249.         ULONG GetXRefBaseAttrsA(struct TagItem *);
  250.  
  251.         ULONG GetXRefBaseAttrs(ULONG ,...);
  252.  
  253.     FUNCTION
  254.         This function gets global attributes of the xref.library. You must
  255.         pass a pointer to the appropriate type for each Tag in the ti_Data
  256.         field. See TAGS for the attributes.
  257.  
  258.     TAGS
  259.         XREFBA_List (struct List *) - gets a pointer to the internal xref
  260.             file list. If you want to step through the list you must lock
  261.             the XRefBase via a LockXRefBase()/UnlockXRefBase() call pair.
  262.             If you do not, the list may be corrupt, because another is
  263.             changing the list via XR_LoadXRef()/XR_ExpungeXRef() calls.
  264.  
  265.         XREFBA_LineLength (UWORD) - gets the line length, which is used by
  266.             the dynamic node to layout the page.
  267.  
  268.         XREFBA_Columns (UWORD) - gets the number of columns, which defines
  269.             the layout of a page of a dynamic node
  270.  
  271.         XREFBA_DefaultLimit - (ULONG) gets default maximal number of matched
  272.             xref entries by a ParseXRef() call.This value will be overwritten
  273.             by the XREFA_Limit tag for the ParseXRef() function.
  274.  
  275.         XREFBA_XRefDir - (STRPTR) gets the default directory for all
  276.             xreffiles.
  277.  
  278.     INPUTS
  279.         tagList (struct TagItem *) - pointer to a TagItem array
  280.         Tag1 (ULONG) - first tag in the varargs stub
  281.  
  282.     RESULTS
  283.         num (ULONG) - number of tags processed
  284.  
  285.     SEE ALSO
  286.         SetXRefBaseAttrsA(),LoadXRefPrefs(),LockXRefBase(),UnlockXRefBase()
  287.  
  288. xref.library/GetXRefConfigDir                    xref.library/GetXRefConfigDir
  289.  
  290.     NAME
  291.         GetXRefConfigDir - returns the xref configuration path
  292.  
  293.     SYNOPSIS
  294.         GetXRefConfigDir(buffer,size);
  295.                            A0    D0
  296.  
  297.         void GetXRefConfigDir(STRPTR ,ULONG );
  298.  
  299.     FUNCTION
  300.         returns in the given buffer , the current xref configuration 
  301.         directory. If the buffer would overflow , it is truncated. Thus
  302.         you should provide a buffer of a appropriate length for a path !
  303.  
  304.     INPUTS
  305.         buffer (STRPTR) - pointer to a memory area to hold the path
  306.         size (ULONG) - number of bytes of the memory area
  307.  
  308.     RESULTS
  309.         none
  310.  
  311.     SEE ALSO
  312.  
  313. xref.library/GetXRefFileAttrsA                  xref.library/GetXRefFileAttrsA
  314.  
  315.     NAME
  316.         GetXRefFileAttrsA - get some attributes of a given xreffile
  317.         GetXRefFileAttrs - varargs stub for GetXRefFileAttrsA()
  318.  
  319.     SYNOPSIS
  320.         num = GetXRefFileAttrsA(xreffile,tagList);
  321.          D0                        A0      A1
  322.  
  323.         num = GetXRefFileAttrs(xreffile,tag1,...);
  324.  
  325.         ULONG GetXRefFileAttrsA(struct XRefFileNode *,struct TagItem *);
  326.  
  327.         ULONG GetXRefFileAttrs(struct XRefFileNode *,Tag ,...);
  328.  
  329.     FUNCTION
  330.         this function gets information about a given xreffile. The handle
  331.         for the xreffile can you get via a call to FindXRefFile() or by
  332.         stepping through the global xreffile list, which you can get with
  333.         the GetXRefBaseAttrsA() function. This is the only way to get infor-
  334.         mation about a xreffile without the name, which can be accessed in
  335.         the ln_Name field of the Node (Perhaps only for displaying in a
  336.         ListView).
  337.         NOTE: You must provide a pointer to the appropriate type for each tag
  338.         in the ti_Data field of the tagitem array.
  339.  
  340.     TAGS
  341.         XREFA_Category (STRPTR) - category of this xreffile
  342.  
  343.         XREFA_Index (BOOL) - indicates , if there exists an index array
  344.             for all entries of this xreffile or not.
  345.  
  346.         XREFA_Priority (BYTE) - priority of this xreffile
  347.  
  348.         XREFA_Lock (BOOL) - returns, if this xreffile is locked or not.
  349.  
  350.         XREFA_Name (STRPTR) - returns a pointer to the xreffile name.
  351.  
  352.         XREFA_VersTag (STRPTR) - returns a pointer to the version string of
  353.             this xreffile or NULL.
  354.  
  355.         XREFA_Path (STRPTR) - returns the global path for all entries in this
  356.             xreffile.
  357.  
  358.         XREFA_Length (ULONG) - returns the number of bytes used for this
  359.             xreffile.
  360.  
  361.     INPUTS
  362.         xreffile (struct XRefFileNode *) - handle for the xreffile
  363.         tagList (struct TagItem *) - tag array with tags you wish information
  364.             for.
  365.         tag1 (ULONG) first tag in the varargs stub.
  366.  
  367.     RESULTS
  368.         num (ULONG) - number of tags processed
  369.  
  370.     SEE ALSO
  371.         FindXRefFile(), SetXRefFileAttrsA()
  372.  
  373. xref.library/LoadXRefPrefs                          xref.library/LoadXRefPrefs
  374.  
  375.     NAME
  376.         LoadXRefPrefs - load a prefs file for the xref.library
  377.  
  378.     SYNOPSIS
  379.         success = LoadXRefPrefs(file);
  380.            D0                     A0
  381.  
  382.         ULONG LoadXRefPrefs(STRPTR );
  383.  
  384.     FUNCTION
  385.         loads the specified prefs file and sets up the xref.library
  386.         attributes to the values given in this file.The file must be an ASCII
  387.         text, which is line oriented.Each line is interpreted to one of the
  388.         following templates :
  389.             - AUTOOPEN/S,FILE/K/A,XREFPRI/N/K,LOCK/S,INDEX/S
  390.             - AUTOLOAD/S,FILE/K/A,XREFPRI/N/K,LOCK/S,INDEX/S
  391.             - MAINPAGE/S,LINELENGTH/N/K/A,COLUMNS/N/K/A
  392.             - CLEANUP/S,FORCE/S
  393.             - XREFDIR/S,DIR/K/A
  394.  
  395.         The AUTOOPEN-Line :
  396.  
  397.         This type of an entry may exists several times in a prefs file.
  398.         It specifies the xreffile, which is opened during parsing of this
  399.         file. The specified arguments are passed to the XR_LoadXRef()
  400.         function, thus see this doc.
  401.  
  402.         The AUTOLOAD-Line :
  403.  
  404.         This type specifies xreffiles, which should be automatically loaded,
  405.         if an entry wasn't found in the xreffiles in memory !
  406.  
  407.         The MAINPAGE-Line :
  408.  
  409.         This entry specifies the line length and the column number, which
  410.         will be used for the "XRef-Library Main Page" and all dynamic nodes.
  411.         Thus you can set these values appropriate to your screen/window
  412.         resolution. This works only under V40 and above. In V39 and below all
  413.         dynamic nodes have just one entry per line !.
  414.  
  415.         The CLEANUP-Line :
  416.  
  417.         If this line appears in a prefs file, all xreffiles are flushed
  418.         form the memory. And if you specify the FORCE switch, all locked
  419.         xreffiles are also flushed.
  420.  
  421.         The XREFPATH-Line :
  422.  
  423.         If you specify this line the path is used as the default xreffile
  424.         path.
  425.  
  426.     INPUTS
  427.         file (STRPTR) - prefs file to load
  428.  
  429.     RESULTS
  430.         TRUE for success , FALSE to indicate an error (see IoErr() result for
  431.         the reason) !
  432.  
  433.     SEE ALSO
  434.         XR_LoadXRef(), XR_ExpungeXRef()
  435.  
  436. xref.library/LockXRefBase                            xref.library/LockXRefBase
  437.  
  438.     NAME
  439.         LockXRefBase - locks the base of the xref.library
  440.  
  441.     SYNOPSIS
  442.         handle = LockXRefBase(key);
  443.           D0                  D0
  444.  
  445.         ULONG LockXRefBase(ULONG);
  446.  
  447.     FUNCTION
  448.         This function locks the xref.library base. The key specifies, which
  449.         internal resource of the xref.library should be locked. At the moment
  450.         there is only a value of zero valid. This locks the whole library
  451.         base. But in future it may exists more different resource types, thus
  452.         you must pass zero at this time, to be compatible in future !!!
  453.  
  454.     INPUTS
  455.         key (ULONG) - key , which specify the internal resource to lock. Only
  456.             zero is valid now.
  457.  
  458.     RESULTS
  459.         handle (ULONG) - handle to pass to the UnlockXRefBase() call
  460.  
  461.     SEE ALSO
  462.         UnlockXRefBase(), GetXRefBaseAttrsA(), SetXRefBaseAttrsA()
  463.  
  464. xref.library/ParseXRef                                  xref.library/ParseXRef
  465.  
  466.     NAME
  467.         ParseXRef - parses the xref lists for a given pattern or name
  468.         ParseXRefTags - varargs stub for ParseXRef
  469.  
  470.     SYNOPSIS
  471.         success = ParseXRef(string,tagList);
  472.          D0                   A0     A1
  473.  
  474.         success = ParseXRefTags(string,tag1,...);
  475.  
  476.         ULONG ParseXRef(STRPTR ,struct TagItem *);
  477.  
  478.         ULONG ParseXRefTags(STRPTR ,Tag ,...);
  479.  
  480.     FUNCTION
  481.         this function parses the specified xref lists for a given pattern
  482.         or name, according to the XREFA_Matching tag value. If this function
  483.         finds a xref entry, the callback function provided by XREFA_ParseHook
  484.         is called with PM_XREF message. This callback function is called in
  485.         2.0 standard Hook way :
  486.            func(REGA0 struct Hook *hook,REGA2 struct XRefFileNode *xrnode,
  487.                 REGA1 struct pmXRef *msg);
  488.  
  489.     INPUTS
  490.         string (STRPTR) - string or pattern to search for
  491.         tagList (struct TagItem *) - TagItem list with required/optional
  492.             arguments
  493.  
  494.     TAGS
  495.         XREFA_XRefHook (struct Hook *) - pointer to a hook structure with
  496.             the callback function, which is called if a xref entry matches
  497.             or a new xref file or file is parsed.If you return a non zero
  498.             value, the parse is suspended, if you return zero the parse
  499.             goes on. The hook function must support at least the XRM_XREF
  500.             message. Currently the following attributes are used in the
  501.             msg->xref_Attrs field :
  502.  
  503.                 ENTRYA_Type, ENTRYA_Name, ENTRYA_Line, ENTRYA_File,
  504.                 ENTRYA_NodeName, XREFA_Path, XREFA_Name.
  505.  
  506.             THIS TAG IS REQUIRED !
  507.  
  508.         XREFA_Category (STRPTR) - category pattern string to specify the
  509.             category for the search. If no category is specified all
  510.             categories matches.
  511.  
  512.         XREFA_CategoryParsed (STRPTR) - a parsed category pattern using the
  513.             ParsePatternNoCase() function. This will speedup parsing, if you
  514.             call this function a lot with the same category pattern.
  515.  
  516.         XREFA_File (STRPTR) - file to parse. The name must be a real path,
  517.             because the comparision is made by the lock to the file.This 
  518.             tag overrides the XREFA_Category tag.
  519.  
  520.         XREFA_Limit (ULONG) - maximal number of matched xref entries. This
  521.             tag overwrites the DefaultLimit of the library base.
  522.  
  523.         XREFA_Matching (ULONG) - mode for the matching mechanism one of the
  524.             following modes should specified :
  525.               XREFMATCH_PATTERN_CASE       - uses MatchPattern() (default)
  526.               XREFMATCH_PATTERN_NOCASE     - uses MatchPatternNoCase()
  527.               XREFMATCH_COMPARE_CASE       - uses strcmp()
  528.               XREFMATCH_COMPARE_NOCASE     - uses Stricmp()
  529.               XREFMATCH_COMPARE_NUM_CASE   - uses strncmp(string,xrefentry,
  530.                                                           strlen(string))
  531.               XREFMATCH_COMPARE_NUM_NOCASE - uses Strnicmp(string,xrefentry,
  532.                                                            strlen(string))
  533.  
  534.         XREFA_AcceptTypes (ULONG *) - ~0 terminated array, which defines
  535.             explicitly the types, which should be used. For example the
  536.             array ULONG mytypes[] = {XREFT_GENERIC,XREFT_FUNCTION,~0} accept
  537.             only entries of the these two types.
  538.  
  539.         XREFA_RejectTypes (ULONG *) - ~0 terminated array, which defines
  540.             types which should not be used. For example the array
  541.             ULONG mytypes2[] = {XREFT_TYPEDEF,XREFT_FIELD,~0} excludes these
  542.             types.
  543.  
  544.     RESULTS
  545.         TRUE for success, that the function has parsed all xref nodes with
  546.         the given parameters. FALSE for an error code see IoErr() to get the
  547.         reason.
  548.  
  549.     NOTES
  550.         this function needs at least the tag XREFA_ParseHook, to get an valid
  551.         hook function pointer to call for any messages.
  552.  
  553.     SEE ALSO
  554.         XR_LoadXRef(), dos.library/ParsePattern(), dos.library/MatchPattern()
  555.         
  556.         dos.library/ParsePatternNoCase(), dos.library/MatchPatternNoCase(),
  557.         utility.library/Stricmp(), utility.library/Strnicmp(), c.lib/strcmp()
  558.         
  559.         c.lib/strncmp()
  560.  
  561. xref.library/RemoveXRefDynamicNode          xref.library/RemoveXRefDynamicNode
  562.  
  563.     NAME
  564.         RemoveXRefDynamicNode - removes the xref.library dynamic node host
  565.  
  566.     SYNOPSIS
  567.         success = RemoveXRefDynamicNode();
  568.  
  569.         BOOL RemoveXRefDynamicNode(void);
  570.  
  571.     FUNCTION
  572.         this removes the previously installed xref.library dynamic node host
  573.         from the amigaguide system.
  574.  
  575.     INPUTS
  576.         none
  577.  
  578.     RESULTS
  579.         TRUE , if the dynamic node is removed. FALSE if not.
  580.  
  581.     SEE ALSO
  582.         AddXRefDynamicNode()
  583.  
  584. xref.library/SetXRefBaseAttrsA                  xref.library/SetXRefBaseAttrsA
  585.  
  586.     NAME
  587.         SetXRefBaseAttrsA - set global attributes of the xref.library
  588.         SetXRefBaseAttrs - varargs stub for SetXRefBaseAttrsA()
  589.  
  590.     SYNOPSIS
  591.         num = SetXRefBaseAttrsA(tagList);
  592.          D0                    A0
  593.  
  594.         num = SetXRefBaseAttrs(Tag1,...);
  595.  
  596.         ULONG SetXRefBaseAttrsA(struct TagItem *);
  597.  
  598.         ULONG SetXRefBaseAttrs(ULONG,...);
  599.  
  600.     FUNCTION
  601.         This function sets some global attributes of the xref.library.
  602.         Which attributes are changeable see TAGS.
  603.  
  604.     TAGS
  605.         XREFBA_LineLength - (UWORD) sets number of characters per line for
  606.             the dynamic node. In conjunction with the XREFBA_Columns
  607.             attribute you can specify your individual page layout.
  608.  
  609.         XREFBA_Columns - (UWORD) sets number of columns for the dynamic node.
  610.             If you specify for example 3 columns and 90 chars per line, the
  611.             dynamic node uses 3 columns with 30 characters.
  612.  
  613.         XREFBA_DefaultLimit - (ULONG) sets default maximal number of matched
  614.             xref entries by a ParseXRef() call.This value will be overwritten
  615.             by the XREFA_Limit tag for the ParseXRef() function.
  616.  
  617.         XREFBA_XRefDir - (STRPTR) sets the default dir for all xreffiles.
  618.             This dir is used as the current directory, during the
  619.             XR_LoadXRef() call.Thus if you use only filenames without any
  620.             dir parts all xreffile can be placed in this directory.
  621.             This tag changes the XREFDIR env variable !
  622.  
  623.     INPUTS
  624.         tagList (struct TagItem *) - pointer to a TagItem array
  625.         Tag1 (ULONG) - first tag in the varargs stub
  626.  
  627.     RESULTS
  628.         num (ULONG) - number of tags processed
  629.  
  630.     NOTE
  631.         You don't need to call LockXRefBase()/UnlockXRefBase() pair. This
  632.         is done by this function internally.
  633.  
  634.     SEE ALSO
  635.         GetXRefBaseAttrsA(), LoadXRefPrefs()
  636.  
  637. xref.library/SetXRefFileAttrsA                  xref.library/SetXRefFileAttrsA
  638.  
  639.     NAME
  640.         SetXRefFileAttrsA - set xreffile attributes
  641.         SetXRefFileAttrs - varargs stub for SetXRefFileAttrsA
  642.  
  643.     SYNOPSIS
  644.         num = SetXRefFileAttrsA(xreffile,taglist);
  645.          D0                        A0      A1
  646.  
  647.         num = SetXRefFileAttrs(xreffile,tag1,...);
  648.  
  649.         ULONG SetXRefFileAttrsA(struct XRefFileNode *,struct TagItem *);
  650.  
  651.         ULONG SetXRefFileAttrs(struct XRefFileNode *,Tag ,...);
  652.  
  653.     FUNCTION
  654.         this function sets some attributes of the given xreffile. The handle
  655.         for the xreffile can you get via a call to FindXRefFile() or by
  656.         stepping through the global xreffile list, which you can get with
  657.         the GetXRefBaseAttrsA() function.
  658.         The only way to change attributes of a xreffile is to call this
  659.         function ! See TAGS for the attributes to be changed.
  660.  
  661.     TAGS
  662.         XREFA_Priority (BYTE) - new priority of this xreffile
  663.  
  664.         XREFA_Index (BOOL) - if set to TRUE, this function tries to allocate
  665.             an index buffer and build an index for binary search.If this
  666.             fails, this tag is interpreted as not processed.
  667.             If you set this tag to FALSE, a previously allocated index buffer
  668.             is deallocated.
  669.  
  670.         XREFA_Lock (UWORD) - if set to XREF_LOCK, this xreffile is locked,
  671.             thus it isn't removed during a memory flush. If set to 
  672.             XREF_UNLOCK, the lock is removed.
  673.  
  674.     INPUTS
  675.         xreffile (struct XRefFileNode *) - handle for the xreffile
  676.         tagList (struct TagItem *) - tag array with tags you wish to set
  677.         tag1 (ULONG) - first tag in the varargs stub.
  678.  
  679.     RESULTS
  680.         num (ULONG) - number of tags processed
  681.  
  682.     SEE ALSO
  683.         FindXRefFile(), GetXRefFileAttrsA()
  684.  
  685. xref.library/UnlockXRefBase                        xref.library/UnlockXRefBase
  686.  
  687.     NAME
  688.         UnlockXRefBase - unlocks the xref.library base
  689.  
  690.     SYNOPSIS
  691.         UnlockXRefBase(handle);
  692.                          D0
  693.  
  694.         void UnlockXRefBase(ULONG);
  695.  
  696.     FUNCTION
  697.         This function unlocks the xref.library base, which was locked via a
  698.         previously LockXRefBase() call. You must pass the handle you get from
  699.         the LockXRefBase() call.This handle specifies the internal resource
  700.         to unlock.
  701.  
  702.     INPUTS
  703.         handle (ULONG) - handle from a call to LockXRefBase()
  704.  
  705.     RESULTS
  706.         none
  707.  
  708.     SEE ALSO
  709.         LockXRefBase(), GetXRefBaseAttrsA(), SetXRefBaseAttrsA()
  710.  
  711. xref.library/WriteXRefFileEntryA              xref.library/WriteXRefFileEntryA
  712.  
  713.     NAME
  714.         WriteXRefFileEntryA - writes a xref entry in the xreffile
  715.         WriteXRefFileEntry - varargs stub for WriteXRefFileEntryA
  716.  
  717.     SYNOPSIS
  718.         success = WriteXRefFileEntryA(handle,taglist);
  719.           D0                           A0     A1
  720.  
  721.         success = WriteXRefFileEntry(handle,tag1,...);
  722.  
  723.         ULONG WriteXRefFileEntryA(struct XRefFileHandle *,struct TagItem *);
  724.  
  725.         ULONG WriteXRefFileEntry(struct XRefFileHandle *,Tag ,...);
  726.  
  727.     FUNCTION
  728.         this function writes a xref entry in the specified xreffile. The
  729.         entries are fully buffered at the moment, so the entries are only
  730.         written to disk, if you call CloseXRefFile().The entries are sorted
  731.         in case-sensetive mode. The file table are build automatically.
  732.         If in the current xreffile exists a entry with the exact ENTRY_Name
  733.         and ENTRY_File, the function fails with the IoErr() set to
  734.         ERROR_OBJECT_EXISTS !
  735.  
  736.     TAGS
  737.         ENTRYA_Type (ULONG) - specifies the type of the entry. This tag is
  738.             REQUIRED. Valid types for now are :
  739.                 XREFT_GENERIC - generic (AmigaGuide node)
  740.                 XREFT_FUNCTION - a library function
  741.                 XREFT_COMMAND - a device command
  742.                 XREFT_INCLUDE - a include file
  743.                 XREFT_MACRO - a define macro
  744.                 XREFT_STRUCT - a structure definition
  745.                 XREFT_FIELD - a field name of a structure
  746.                 XREFT_TYPEDEF - a typedef
  747.                 XREFT_DEFINE - a normal define
  748.  
  749.         ENTRYA_Name (STRPTR) - specifies the name of the entry. This tag is
  750.             REQUIRED !
  751.  
  752.         ENTRYA_File (STRPTR) - specifies the relative path for the file
  753.             including the filename.
  754.  
  755.         ENTRYA_Line (ULONG) - specifies the line number in the file.
  756.  
  757.         ENTRYA_NodeName (STRPTR) - specifies the amigaguide node name. If
  758.             this isn't set the ENTRYA_Name will be used for the nodename.
  759.  
  760.         ENTRYA_CheckMode (ULONG) - one of the following modes :
  761.                 ENTRYCHECK_NONE : include the entry without any checking
  762.                 ENTRYCHECK_NAME : include the entry only, if no entry exists
  763.                                   with this name
  764.                 ENTRYCHECK_FILE : include the entry, if there exists a entry
  765.                                   with this name, but in a different file !
  766.             default is : ENTRYCHECK_NAME !
  767.  
  768.     INPUTS
  769.         handle (struct XRefFileHandle *) - handle pointer returned from
  770.             CreateXRefFileA()
  771.         taglist (struct TagItem *) - pointer to th e first element of the
  772.             tagitem array
  773.         tag1 (Tag) - first tag in the varargs stub
  774.  
  775.     RESULTS
  776.         success (ULONG) - TRUE for success , FALSE for a failure reason see
  777.             IoErr().
  778.  
  779.     SEE ALSO
  780.         CreateXRefFileA(), CloseXRefFile()
  781.  
  782. xref.library/XR_ExpungeXRef                        xref.library/XR_ExpungeXRef
  783.  
  784.     NAME
  785.         XR_ExpungeXRef - expunge a given or all xreffile from memory
  786.         XR_ExpungeXRefTags - varargs stub for XR_ExpungeXRef()
  787.  
  788.     SYNOPSIS
  789.         num = XR_ExpungeXRef(tagList);
  790.                                 A0
  791.  
  792.         num = XR_ExpungeXRefTags(tag1,...);
  793.  
  794.         ULONG XR_ExpungeXRef(struct TagItem *);
  795.  
  796.         ULONG XR_ExpungeXRefTags(ULONG ,...);
  797.  
  798.     FUNCTION
  799.         expunges a given or all xreffiles from memory. This must specified
  800.         via TAGS. A NULL pointer for the tagList means, that all xreffiles
  801.         should be expunged !
  802.  
  803.     INPUTS
  804.         tagList (struct TagItem *) - tags, which specify which xreffile(s)
  805.             should be expunged
  806.  
  807.     TAGS
  808.         XREFA_Category (STRPTR) - expunge all xreffiles, which belongs to the
  809.             specified category (pattern) !
  810.  
  811.         XREFA_File (STRPTR) - expunge only the given file, if you have setup
  812.             the global XRefPath, this can be only the filename.
  813.  
  814.         XREFA_Lock (ULONG) - if the data value if XREF_UNLOCK expunge also
  815.             xreffiles, which are locked
  816.  
  817.         XREFA_XRefHook (struct Hook *) - callback function to confirm the
  818.             expunge of the given xreffile. The function is called in the
  819.             Amiga 2.0 standard way with the object pointer to the
  820.             XRefFileNode structure (struct XRefFileNode *) and the message
  821.             XRM_EXPUNGE : (struct xrmExpunge *) !
  822.  
  823.     RESULTS
  824.         number of expunged files
  825.  
  826.     SEE ALSO
  827.         XR_LoadXRef(), GetXRefFileAttrsA(), SetXRefFileAttrsA()
  828.  
  829. xref.library/XR_LoadXRef                              xref.library/XR_LoadXRef
  830.  
  831.     NAME
  832.         XR_LoadXRef - load a xreffile into the memory
  833.         XR_LoadXRefTags - varargs stub for XR_LoadXRef()
  834.  
  835.     SYNOPSIS
  836.         xrefnode = XR_LoadXRef(file,tagList);
  837.          D0                    A0     A1
  838.         
  839.         xrefnode = XR_LoadXRefTags(file,tag1,...);
  840.  
  841.         struct XRefFileNode *XR_LoadXRef(STRPTR ,struct TagItem *);
  842.  
  843.         struct XRefFileNode *XR_LoadXRefTags(STRPTR,ULONG,...);
  844.  
  845.     FUNCTION
  846.         loads the specified file in the memory and adds it to the global
  847.         xref list in the library.
  848.  
  849.     INPUTS
  850.         file (STRPTR) - file to load into the memory
  851.         tagList (struct TagItem *) - pointer to a TagItem array with more
  852.             arguments see TAGS.
  853.  
  854.     TAGS
  855.         XREFA_Category (STRPTR) - category for the xreffile, if no category
  856.             is specified, it searches for a category definition in the
  857.             xreffile. If there is also no specified, then this file is a
  858.             global xreffile and is parsed every time ParseXRef() is called.
  859.  
  860.         XREFA_Priority (BYTE) - priority for this xreffile. This priority is
  861.             used to insert the xreffile in the global xref list using the
  862.             exec.library/Enqueue() function.Thus if a xreffile has a high
  863.             priority it is parsed before any xreffile with lower priority.
  864.  
  865.         XREFA_Lock (ULONG) - You can pass XREF_LOCK or XREF_UNLOCK here.
  866.             If you pass XREF_LOCK, this xreffile is locked and can be removed
  867.             only by a XR_ExpungeXRef() call with the XREF_UNLOCK value. Or
  868.             by changing the lock mode via a SetXRefFileAttrsA() call.
  869.             If the xreffile is locked it can't removed by a memory flush !!!
  870.  
  871.         XREFA_CustomHook (struct Hook *) - callback function to handle a
  872.             specified xreffile. This is used if someone has a own xreffile
  873.             format !
  874.             Not implemented yet !
  875.  
  876.         XREFA_File (STRPTR) - overwrites the filename from the first argument
  877.  
  878.         XREFA_Name (STRPTR) - name of the xreffile, this name is used instead
  879.             of the filename
  880.  
  881.         XREFA_Index (BOOL) - if TRUE, this function tries to allocate an
  882.             index buffer for all entries. So the if this is going allright,
  883.             each search function uses the binary search algorithm. If it is
  884.             FALSE it deallocates this index buffer and the search is then
  885.             sequential.
  886.  
  887.         XREFA_XRefHook (struct Hook *) - callback function to notify, that
  888.             the given xreffile was loaded.With object (struct XRefFileNode *)
  889.             and message XRM_LOAD: (struct xrmLoad *) !
  890.  
  891.     RESULTS
  892.         NULL for a failure (see IoErr() for the reason),otherwise the pointer
  893.         to the XRefFileNode structure !
  894.  
  895.         Special error codes :
  896.  
  897.         ERROR_OBJECT_WRONG_TYPE - indicates , that the given file has not the
  898.             right fileformat (wrong fileformat version) !
  899.  
  900.         ERROR_NO_MORE_ENTRIES - indicates , that the given file has no
  901.             entries. Thus this file is obsolete !
  902.  
  903.     SEE ALSO
  904.         XR_ExpungeXRef(), ParseXRef(), SetXRefFileAttrsA(), 
  905.         GetXRefFileAttrsA(), libraries/xref.h
  906.  
  907.